HAL SD migration: List of applicable concepts

This section provides information about the HAL SD architecture concepts relevant to STM32 HAL1 to HAL2 migration.

Concepts for SD

Concept	Description here
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: HAL_SD_Init(): initializes the handle and links it to an SD instance. HAL_SD_SetConfig(): sets the configuration for the SD peripheral.
Removal and conversion of init structure to configuration structure	The init structure has been removed from the handle and converted into hal_sd_config_t structure.
Renaming of the handle structure	The handle structure has been renamed to hal_sd_handle_t.
Renaming unitary init structures	The structure SD_InitTypeDef is no longer available and replaced by hal_sd_config_t.
Remove MspInit and MspDeInit callbacks	hal_sd_MspInit() and hal_sd_MspDeInit() are no longer available, they are replaced by a user sequence to initialize and configure the SD.
Unitary configuration APIs	New APIs are introduced to individually Set and Get specific SD configuration parameters, allowing for more granular control and flexibility: HAL_SD_SetDataTimeout(), HAL_SD_GetDataTimeout().
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each SD event. These functions are used to register callback functions for different SD events.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL SD driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL API status returns	The HAL SD functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL SD driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and states are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Refactor the HAL inclusion model.	HAL2 introduces a more structured and flexible inclusion model compared to HAL1, with a new entry point, conditional flags for module activation, consolidation of extension APIs. User configuration is propagated through dedicated header files.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL SD header file remains and all macros, define statements, and functions from hal_sd_ex.h have been moved to hal_sd.h.
Rename LL core drivers to stm32_ppp_core.h/.c to avoid confusion with user LL drivers.	LL core driver has been renamed from stm32tnxx_ll_sdmmc.h/.c to stm32tnxx_sdmmc_core.h/.c.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	HAL SD provides a new API to retrieve clock frequency HAL_SD_GetClockFreq()
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including SD instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL SD resources and data structures are now prefixed with HAL_SD.

Other HAL SD changes

Concept	Consideration
Increase performance and add the missing APIs for linked-list management.	New linked-list management features are added, and most linked-list operations are consolidated in a new HAL. This HAL, called HAL Q, provides advanced linked-list features and is shared between multiple HAL drivers.